home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / 3DBorder.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  12.5 KB  |  376 lines
  1. '\"
  2. '\" Copyright 1990 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/3DBorder.man,v 1.9 92/06/26 16:15:47 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tk_Get3DBorder tk
  189. .BS
  190. .SH NAME
  191. Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_Free3DBorder \- draw borders with three-dimensional appearance
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tk.h>\fR
  195. .sp
  196. Tk_3DBorder
  197. \fBTk_Get3DBorder(\fIinterp, tkwin, colorMap, colorName\fB)\fR
  198. .sp
  199. void
  200. \fBTk_Draw3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
  201. .sp
  202. void
  203. \fBTk_Fill3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
  204. .sp
  205. void
  206. \fBTk_Draw3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
  207. .sp
  208. void
  209. \fBTk_Fill3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
  210. .sp
  211. void
  212. \fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
  213. .sp
  214. char *
  215. \fBTk_NameOf3DBorder(\fIborder\fB)\fR
  216. .sp
  217. .VS
  218. XColor *
  219. \fBTk_3DBorderColor(\fIborder\fB)\fR
  220. .VE
  221. .sp
  222. \fBTk_Free3DBorder(\fIborder\fB)\fR
  223. .SH ARGUMENTS
  224. .AS "Tk_3DBorder" borderWidth
  225. .AP Tcl_Interp *interp in
  226. Interpreter to use for error reporting.
  227. .AP Tk_Window tkwin in
  228. Token for window in which border will be drawn.
  229. .AP Colormap colormap in
  230. Colormap from which to allocate colors.  If None, then the default
  231. colormap for \fItkwin\fR's screen is used.
  232. .AP Tk_Uid colorName in
  233. Textual description of color corresponding to background (flat areas).
  234. Illuminated edges will be brighter than this, and shadowed edges will
  235. be darker than this.
  236. .AP Display *display in
  237. Xlib pointer indicating display with which drawable is associated.
  238. .AP Drawable drawable in
  239. X token for window or pixmap;  indicates where border is to be drawn.
  240. .AP Tk_3DBorder border in
  241. Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
  242. .AP int x in
  243. X-coordinate of upper-left corner of rectangle describing border.
  244. .AP int y in
  245. Y-coordinate of upper-left corner of rectangle describing border.
  246. .AP int width in
  247. Width of rectangle describing border, in pixels.
  248. .AP int height in
  249. Height of rectangle describing border, in pixels.
  250. .AP int borderWidth in
  251. Width of border in pixels. Positive means border is inside rectangle
  252. given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
  253. border is outside rectangle.
  254. .AP int relief in
  255. Indicates 3-D position of interior of rectangle relative to exterior;
  256. should be  TK_RELIEF_RAISED or TK_RELIEF_SUNKEN (may also be TK_RELIEF_FLAT
  257. for \fBTk_Fill3DRectangle).
  258. .AP XPoint *pointPtr in
  259. Pointer to array of points describing the set of vertices in a polygon.
  260. The polygon need not be closed (it will be closed automatically if it
  261. isn't).
  262. .AP int numPoints in
  263. Number of points at \fI*pointPtr\fR.
  264. .AP int polyBorderWidth in
  265. Width of border in pixels.  If positive, border is drawn to left of
  266. trajectory given by \fIpointPtr\fR;  if negative, border is drawn to
  267. right of trajectory.
  268. .AP int leftRelief in
  269. Height of left side of polygon's path relative to right.  TK_RELIEF_RAISED
  270. means left side should appear higher, TK_RELIEF_SUNKEN means right side
  271. should appear higher.  For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT
  272. may also be specified to indicate no difference in height.
  273. .BE
  274.  
  275. .SH DESCRIPTION
  276. .PP
  277. These procedures provide facilities for drawing window borders in a
  278. way that produces a three-dimensional appearance.  \fBTk_Get3DBorder\fR
  279. allocates colors and Pixmaps needed to draw a border in the window
  280. given by the \fItkwin\fR argument.  The \fIcolormap\fR argument
  281. specifies a Colormap to use for allocating colors, and the \fIcolorName\fR
  282. argument indicates what colors should be used in the border.  \fIColorName\fR
  283. may be any value acceptable to \fBTk_GetColor\fR.  The color indicated
  284. by \fIcolorName\fR will not actually be used in the border;  it indicates
  285. the background color for the window (i.e. a color for flat surfaces).
  286. The illuminated portions of the border will appear brighter than indicated
  287. by \fIcolorName\fR, and the shadowed portions of the border will appear
  288. darker than \fIcolorName\fR.
  289. .PP
  290. \fBTk_Get3DBorder\fR returns a token that may be used in later calls
  291. to \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating information
  292. for the border (e.g. \fIcolorName\fR isn't a legal color specifier),
  293. then NULL is returned and an error message is left in \fIinterp->result\fR.
  294. .PP
  295. Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
  296. invoked to draw the border.  The \fIdisplay\fR and \fIdrawable\fR
  297. arguments specify a window or pixmap in which the border is to be
  298. drawn.  \fIDrawable\fR need not refer to the same window as the
  299. \fItkwin\fR used to create the border, but it must refer to a compatible
  300. pixmap or window:  one associated with the same display and with the
  301. same depth as the \fItkwin\fR used to create the border.
  302. The \fIx\fR, \fIy\fR, \fIwidth\fR, and
  303. \fIheight\fR arguments define the bounding box of the border region
  304. within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and
  305. \fIwidth\fR and \fIheight\fR are the dimensions of the window), and
  306. \fIborderWidth\fR specifies the number of pixels actually
  307. occupied by the border.  The \fIrelief\fR argument indicates
  308. which of two three-dimensional effects is desired:
  309. TK_RELIEF_RAISED means that the interior of the rectangle should appear raised
  310. relative to the exterior of the rectangle, and
  311. TK_RELIEF_SUNKEN means that the interior should appear depressed.
  312. .PP
  313. \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
  314. that it first fills the rectangular area with the background color
  315. (one corresponding
  316. to the \fIcolorName\fR used to create \fIborder\fR).  Then it calls
  317. \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
  318. the rectangular area.  The argument \fIrelief\fR indicates the desired
  319. effect:  TK_RELIEF_RAISED means the interior of the rectangle should
  320. appear higher than the exterior;  TK_RELIEF_SUNKEN means the reverse;
  321. and TK_RELIEF_FLAT means no border should be drawn at all (all that
  322. happens is to fill the rectangle with the background color).
  323. .PP
  324. The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
  325. shapes with a three-dimensional appearance.  The \fIpointPtr\fR and
  326. \fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR
  327. indicates how wide the border should be (and on which side of the
  328. trajectory to draw it), and \fIleftRelief\fR indicates which side
  329. of the trajectory should appear raised.  \fBTk_Draw3DPolygon\fR
  330. draws a border around the given trajectory using the colors from
  331. \fIborder\fR to produce a three-dimensional appearance.  If the trajectory is
  332. non-self-intersecting, the appearance will be a raised or sunken
  333. polygon shape.  The trajectory may be self-intersecting, although
  334. it's not clear how useful this is.  If the trajectory contains only
  335. two points, then the result will be a groove or ridge, depending
  336. on whether \fIleftRelief\fR is TK_RELIEF_RAISED or
  337. TK_RELIEF_SUNKEN (respectively).
  338. .PP
  339. \fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR as
  340. \fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR:  it fills
  341. the polygonal area with the background color from \fIborder\fR,
  342. then calls \fBTk_Draw3DPolygon\fR to draw a border around the
  343. area (unless \fIleftRelief\fR is TK_RELIEF_FLAT;  in this case no
  344. border is drawn).
  345. .PP
  346. The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
  347. pixel and/or pixmap of \fItkwin\fR to produce a result compatible
  348. with \fIborder\fR.  For color displays, the resulting background will
  349. just be the color given by the \fIcolorName\fR argument passed to
  350. \fBTk_Get3DBorder\fR when \fIborder\fR was created;  for monochrome
  351. displays, the resulting background
  352. will be a light stipple pattern, in order to distinguish the background from
  353. the illuminated portion of the border.
  354. .PP
  355. Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
  356. will return the \fIcolorName\fR string that was passed to
  357. \fBTk_Get3DBorder\fR to create the border.
  358. .PP
  359. .VS
  360. The procedure \fBTk_3DBorderColor\fR returns the XColor structure
  361. that will be used for flat surfaces drawn for its \fIborder\fR
  362. argument by procedures like \fBTk_Fill3DRectangle\fR.
  363. The return value corresponds to the \fIcolorName\fR passed to
  364. \fBTk_Get3DBorder\fR.
  365. The XColor, and its associated pixel value, will remain allocated
  366. as long as \fIborder\fR exists.
  367. .VE
  368. .PP
  369. When a border is no longer needed, \fBTk_Free3DBorder\fR should
  370. be called to release the resources associated with the border.
  371. There should be exactly one call to \fBTk_Free3DBorder\fR for
  372. each call to \fBTk_Get3DBorder\fR.
  373.  
  374. .SH KEYWORDS
  375. 3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect
  376.